home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d14 / actortut.arc / TUTR3.TXT < prev    next >
Text File  |  1990-10-18  |  9KB  |  215 lines
  1.                        Using Dialog Boxes in Actor
  2.                        ---------------------------
  3.  
  4. By Dan Walker
  5. Copyright (c) 1990 the Whitewater Group, Inc.
  6.  
  7.  
  8. This is the first in a number of articles that will be appearing on 
  9. the BBS.  They are directed towards Actor(R) programmers who are not 
  10. that familiar with Windows.  If  you have a topic you would like 
  11. discussed in this space, please send a message describing your
  12. idea to the sysop.
  13.  
  14. This article is about  using dialog boxes in Actor.  It describes 
  15. what a dialog box is, how you create a dialog box,  and  how you 
  16. incorporate and use dialog boxes with Actor.
  17.  
  18. What is a Dialog Box?
  19. A dialog box is a specialized window that you can use to prompt the 
  20. user for input.  Windows (tm) provides a number of items, called 
  21. controls, that are used as components of a dialog box.  The basic 
  22. control types are:
  23.  
  24.         Static
  25.         Static controls are used to put labels and other informative
  26.         text within the dialog box.
  27.  
  28.         Edit
  29.         Edit controls are used as data entry fields.  These may be no
  30.         bigger than a single character or big enough to enter whole 
  31.         pages of text.
  32.  
  33.         Buttons
  34.         Buttons are used to solicit multiple choice information.  
  35.         Buttons come in a number of different styles:
  36.              
  37.            Push Buttons  
  38.            used to initiate some action, e.g., most dialog boxes 
  39.            have an "OK" button and a "CANCEL" button for ending the
  40.            dialog.
  41.  
  42.            Check Boxes
  43.            used to prompt the user to select all that apply.
  44.  
  45.            Radio Buttons
  46.            used to select one from a group of mutually exclusive
  47.            options.
  48.  
  49.            Group Boxes
  50.            used to visually group items in a dialog.  A group box is
  51.            frequently used in conjunction with a group of radio
  52.            buttons.
  53.             
  54.   
  55.         List boxes
  56.         List boxes are used to present the user with variable-length
  57.         lists of choices.  A good example of this is the file dialog
  58.         box used by an Actor FileWindow.  One of its controls is a 
  59.         list box of available files to edit.  Push buttons are 
  60.         frequently used with list boxes to ask the user to confirm 
  61.         his/her choice.
  62.  
  63.         Scroll bars
  64.         Scroll bars are used to ask the user to specify a value
  65.         within a certain range.  When you set up a scroll bar you 
  66.         specify a beginning and ending range.  When the user slides 
  67.         the thumb of the scroll bar, Windows computes a value that is
  68.         the relative distance from the beginning value given the 
  69.         ending value.  For example, if the beginning and ending 
  70.         values are 1 and  50, sliding the thumb to the middle of the
  71.         bar returns the value 25.
  72.  
  73. Most of the time your dialog boxes will be resources that you 
  74. describe using one of the tools mentioned below and incorporate 
  75. into the .EXE portion of your application.  Actor 2.0 also provides 
  76. the means of dynamically creating dialog boxes.
  77.  
  78. How do I create a dialog box?
  79. There are several ways to create a dialog box.  Some methods for 
  80. creating dialog boxes, as well as sources of additional information 
  81. on using these methods, are listed below:
  82.  
  83.         Use the Whitewater Resource Toolkit.
  84.         This is the easiest way to edit dialog boxes and other 
  85.         Windows resources.  With the Whitewater Resource Toolkit you 
  86.         can design and compile your dialog in one step without 
  87.         leaving Windows and without having to deal with the Microsoft resource
  88.         compiler.  For more information on the Whitewater Resource Toolkit,
  89.         see the Whitewater Resource Toolkit user's manual.
  90.  
  91.         Use DIALOG.EXE, the dialog editor that comes with the Windows
  92.         Software Development Kit.  For more information on how to
  93.         use this tool,  see chapter 10 of the Microsoft Windows Software
  94.         Development Kit Programming Tools Manual.
  95.  
  96.         Use a text editor.  This is the hardest method to use but it
  97.         can be done.  To do this, you need to edit a copy of ACTOR.RC
  98.         and add to it a description of your dialog.  Dialog 
  99.         descriptions or templates are written in the following form:
  100.  
  101.         dialogName DIALOG x, y, width, height
  102.             STYLE style1 | style2 | ...
  103.             BEGIN
  104.                cntrl-type text ID, x, y, width, height, style
  105.                .
  106.                .
  107.             END
  108.  
  109.         for example:
  110.  
  111.         MY_BOX DIALOG 20, 20, 150, 100
  112.           STYLE WS_POPUP | WS_DLGFRAME
  113.           BEGIN
  114.              CTEXT "Test box 1" -1, 0, 10, 150, 8
  115.              DEFPUSHBUTTON "OK" IDOK,50, 50, 32, 14, WS_GROUP
  116.              PUSHBUTTON "CANCEL" IDCANCEL,100,50,32,14,WS_GROUP
  117.           END
  118.  
  119.         This template will produce a dialog box with the text "Test 
  120.         box 1" centered at the top and two buttons, one labeled "OK"
  121.         and the other labeled "CANCEL".  The buttons will have the 
  122.         control IDs of IDOK and IDCANCEL  respectively, which are
  123.         defined in ACTOR.H.  Literal numeric values can also be used.
  124.  
  125.         For more information on creating dialog boxes in this manner,
  126.         see "Programming Windows", Microsoft Press, by Charles 
  127.         Petzold.
  128.  
  129.  
  130.         Use the DialogDesign class to make dynamic dialog boxes.  
  131.         This is a new feature in Actor 2.0.  With this class, you 
  132.         can build a dialog box directly in memory and run it
  133.         immediately.  This type of dialog is not a resource and 
  134.         therefore the following section does not apply.  For more 
  135.         information on DialogDesign objects, see the Actor 2.0 
  136.         Addendum Manual.
  137.  
  138.  
  139. How do I use my dialog box in Actor?
  140. To use your dialog box, it must become part of the .EXE portion of 
  141. Actor.  It is a good policy to keep an untouched copy of ACTOR.EXE,
  142. ACTOR.H, and ACTOR.RC in a safe place.  Start each new application by
  143. making copies of these backup copies.
  144.  
  145. There are several ways to append your dialog box to ACTOR.EXE.  The 
  146. easiest way is to use the Whitewater Resource Toolkit which allows 
  147. you to read and write dialog boxes and other resources directly to 
  148. and from an .EXE file.  If you do not have the Whitewater Resource 
  149. Toolkit, you must use the resource compiler, RC, a Microsoft tool 
  150. that is included with Actor.
  151.  
  152. There are a couple of ways to include your dialog as one of the 
  153. resources available to Actor.  Here is one way:
  154.  
  155.         1. Make your default directory ACTOR\RES.
  156.         2. Edit ACTOR.RC to include texts that are part of your 
  157.            dialog.  If you produced a header file with your dialog
  158.            template, add a line near the top of ACTOR.RC that looks
  159.            like this:
  160.  
  161.                 #include mydialog.h
  162.  
  163.            where "mydialog" is replaced by the name of your header 
  164.            file.  Use the "rinclude" directive to include your dialog
  165.            template:
  166.  
  167.                 rcinclude mydialog.dlg
  168.  
  169.         3. Type: RC ACTOR.RC 
  170.            This will recompile all of the Actor resources, including
  171.            your new dialog, and append them to ACTOR.EXE.
  172.  
  173.  
  174. To use your dialog box in an Actor application, run the copy of Actor
  175. that your dialog box is stored in.  Next design a descendent of the 
  176. Dialog class to work with your dialog.  Your new class should 
  177. minimally implement new versions of the methods "initDialog" and 
  178. "command".  The "initDialog" method can be used to do any startup 
  179. processing that might be necessary such as placing new values in 
  180. edit controls.  The "command" method is the mechanism that allows 
  181. you to respond to events occurring while your dialog box is active.
  182. Typically, your dialog box will have a button or two that, when 
  183. pressed, indicate that the dialog should end.  The "command" usually
  184. uses a select statement to scan for the control Ids of the controls 
  185. in your dialog.  This method is an appropriate place to retrieve 
  186. information from the dialog box.  An example of this is the 
  187. "command" method in InputDialog.  This method tests to see whether the 
  188. "OK" button was pressed and if so, saves the text from the dialog, 
  189. then ends the dialog.
  190.  
  191. Once you have set up these methods you can run your dialog by 
  192. creating an instance of your new dialog class and sending it a 
  193. "runModal" or "runModeless" message:
  194.  
  195.         Sam := new( MyDialog );
  196.         runModal( Sam, "MY_BOX", ThePort );
  197.  
  198. In this example, MyDialog is a descendant of Dialog, MY_BOX is the
  199. name of the dialog described above, and ThePort is a global variable
  200. that is handy to use as the parent for your dialog box.  You do not 
  201. send the "initDialog" and "command" messages; Windows and Actor do 
  202. this for you.  Two good examples of using dialog boxes are built into
  203. Actor.  These are the InputDialog and FileDialog classes.
  204.      
  205. In conclusion, let's review the steps for creating and using a dialog
  206. box:
  207.  
  208.         1. Describe the dialog box.
  209.         2. Compile the dialog box into ACTOR.EXE ( this step isn't
  210.            necessary when using the Whitewater Resource Toolkit ).
  211.         3. Design a descendent of the Dialog class to work with
  212.            instances of your new dialog.
  213.         4. Run your dialog using the "runModal" or "runModeless" 
  214.            message.